`co(4,7);─────────────────── /// Dialog Transfer and Menu construction ────────────────`co();

	  InTUItion's Transfer capabilities is one of its most powerful features.
	It gives you the ability to nest or "transfer" control from one dialog to
	another.  Using this feature gives you almost unlimited flexibility in
	dialog construction.  Here's how it works...

	  The best example of how a transfer works is in the construction program
	itself.  Transfer is used in the Entry dialog.  When this dialog is
	displayed, click on the button marked "Special".  You will see another
	dialog appear containing additional data used by the entry system.  In
	this way, we can prevent cluttering the screen with additional data that
	does not always require modification, yet is only a click or keystroke
	away!

	  To setup a transfer from one dialog to another, you must first have more
	than one dialog created in your TUI.  All you have to do is click on the
	"Transfer" button in the edit dialog for the item from which you wish to
	transfer.  Though this would normally be a button, you can transfer from
	any object except a static text string.  When you click on "Transfer", a
	pick list will appear containing all dialogs within the current TUI.
	Simply pick the desired dialog to which to transfer.

	  We have one more decision to make.  When a dialog is transferred from
	another dialog, we need to know what to do when this dialog is exited.  In
	the case of two dialogs the decision is easy; we simply transfer back to
	the calling dialog.  However, suppose we nest four levels deep: do we
	return to the previous dialog or to the first dialog?  InTUItion allows
	you to control this for greater flexibility.  Each item in the dialog that
	can be set as an exit has two buttons marked "One Level" and "All Levels".
	If you select "One Level", then when this object causes an exit from the
	current dialog, control will be returned to the calling dialog (one level
	below it).  If you select "All Levels", the exit will go through all
	dialogs in the chain, finallly exiting from the very first dialog in the
	chain.  The returned value will be set to the item in that very top dialog
	that caused the exit.  It may sound confusing but it's really quite
	simple. Run the included transfer tutorial and try creating your own and
	you'll have transfer mastered in no time.

	  InTUItion does not support menus as a seperate object or entity.  Menu
	support is part of the UltraWin package.  However, a menu is really just a
	sequence of linked dialogs.  Since we now understand the transfer
	mechanism, we can see how this might work.  The TUICP has a few built in
	features that allow easier construction of dialogs in menu form.

	  To create a basic menu we simply add a dialog to the TUI.  In this case
	however, we add a menu dialog.  Simply select "Add Menu Dialogs" from the
	"Dialogs" menu.  You will be asked to select the number of dialogs to add.
	This corresponds to how many drop down menus to create on the base horiz-
	ontal menu bar.  Let's select eight and click on OK.  You will notice that
	the TUICP adds nine dialogs to the TUI.  The first dialog is the
	horizontal menu bar and the rest are the drop down menus.  If you click
	the right button on the first one and select "Test" from the "Edit" menu,
	you can see the Transfer in action.  It appears as though we have created
	a common drop down menu system; however, we have done much more.  The
	TUICP created nine dialogs that transfer control back and forth in a
	layout that looks like a typical menu system.  The important thing to
	remember here is that the dialogs have nothing to do with menus since
	menus don't really exist in InTUItion.  This means that you can modify the
	dialogs to contain check boxes, strings, icons, even sliders!  You can
	also move them around the screen, transfer control to yet another menu or
	dialog, etc.  The possibilities are unlimited.  Just remember, a menu is
	really a number of dialogs that contain buttons for each menu entry,
	linked together with the transfer capability.  Run the included menu
	tutorial and try creating your own and you'll soon feel quite confortable
	with this versatile menu system.

	NOTE:  While you can create standard drop down menus with the TUICP, and
				 these have there place in many programs, the concept behind the
				 dialogs is to find easier and more intuitive ways to create user
				 interfaces.  You will find that many programs don't need any menus
				 at all, and the ones that do (such as TUICP.EXE) can have a very
				 simple and straightforward menu system that transfers control to
				 other dialogs.


`co(4,7);────────────────── /// Incorporating Dialogs into your programs ──────────────`co();

	  Once your have finished your dialog, the easiest way to incorporate it
	into your program is to let the TUICP do the work for you by generating a
	"C" source code shell to interact with the dialog.  Below is an example
	and an explanation as to how it works.

		First we have the TEST.DEF file that contains the names of all the
	objects within our dialog.  The generated file looks like this.

/**************************************************************************/
/* TEST.DEF                                                               */
/*                                                                        */
/* TUI definitions.  Use these defines as the index parameter for all the */
/* InTUItion functions.                                                   */
/**************************************************************************/

#define  TEST_DLG             0
#define  BOX                  1
#define  ENTRY                2
#define  H_SLIDER             3
#define  V_SLIDER             4
#define  ICON                 5
#define  BUTTON               6

		Second, we have the TEST.C file that contains the actual source
	generated by the TUICP.  The generated file looks like this.

/**************************************************************************/
/* TEST.C                                                                 */
/*                                                                        */
/* Default logic for dialog interaction.                                  */
/**************************************************************************/
#include "t.h"                             /* include the TUI definitions */
#include "TEST.DEF"

/*************/
/* ~interact */
/*           **************************************************************/
/* Shell code for typical dialog interaction.  A pointer to the TUI and   */
/* the define for the dialog are passed.                                  */
/*                                                                        */
/* Pass the DO_NORMAL define to do_dialog if you do not want to have every*/
/* event the do_dialog function does not understand returned to you!      */
/**************************************************************************/
interact( TUI *tuip, int dlg_inx )
{
  int ret_inx, end_flag = OFF;

  draw_dialog(tuip, dlg_inx);
  while (!end_flag)
  {
    ret_inx = do_dialog(tuip, dlg_inx, DO_RETURN_EVENT);
    switch( ret_inx )
    {
      /*---------------- ESC pressed or clicked off dialog ---------------*/
      case NO_SELECTION:
        end_flag = ON;
        break;
     /*---------------------- an event not processable -------------------*/
      case EVENT_RETURNED:
        if (!Event.is_mouse)
        {
        }
      	else switch( Event.key )
        {
        }
        break;
      case BOX:
        break;
      case ENTRY:
        break;
      case H_SLIDER:
        break;
      case V_SLIDER:
        break;
      case ICON:
        break;
      case BUTTON:
        break;
    }
    if ( is_valid_inx(tuip, ret_inx) )
    {
      switch( get_item_type(tuip, ret_inx) )
      {
        case T_BUTTON: case T_ICON:
          deselect(tuip, ret_inx);
          draw_item(tuip, ret_inx);
          break;
      }
    }
  }
  erase_dialog(tuip, dlg_inx);
}
/*** end of interact ***/

/*** END OF FILE ***/

		Now for your main program, you might have something like this:

main()
{
	TUI			Test_tui, *Test_tuip = &Test_tui;
	WINDOW	*desk_wnp;

	load_tui(Test_tuip, "TEST.TUI");				/* read the TUI file from disk  */ 
	init_tui(Test_tuip);										/* init video, mouse, etc   		*/
	desk_wnp = Test_tuip->back_wnp;

	interact(Test_tuip, TEST_DLG);					/* go execute generated function*/

	end_tui(Test_tuip);											/* reset mouse, video, etc			*/
	free_tui(Test_tuip);
}

	  Your main program calls interact with the TUI pointer which has been
	either loaded or linked in, and an index to this dialog.  Remember, a TUI
	file can have many dialogs, this is why we named the dialog when we first
	created it.  You will notice that the interact function draws the dialog
	and calls the core function do_dialog.  This is the main routine that
	interacts with the dialog, returning control to you when an action is
	performed.  Notice the simple switch case processing.  It is almost
	identical to a simply key press switch;  it's really that easy!  All you
	have to do is add the code to handle each event.  We do that next to give
	you a better feel for accessing each object.  Let's start with BOX.

BOX - when the user clicks on the box, do_dialog returns the index of BOX.
			We can then perform any needed action.  Let's just beep for now to
			let the user know he selected the box.

      case BOX:
        tone(1000,91);  									/* beep at 1000 Hz for 1 second */
        break;

ENTRY - when the user clicks on the entry field or tabs to it and presses
				enter, or presses the proper hot key, do_dialog returns the index
				of ENTRY. We can now read the value entered and print it out.
				

		  case ENTRY:
       wn_plst(0,0,((TUI_INPUT *)Test_tuip->base[ENTRY].more.ptr)->text.ptr,
               desk_wnp);
       break;
        
       Looks pretty complicated doesn't it?  Here it is in English.  Get
			 the main array within this TUI, index into it with the ENTRY object,
			 get its more pointer, (which points to an input structure), then get
			 its text pointer which points to the string in question.  Then put
			 this text in the top left corner of the background desktop window
			 created by the init_tui function.  Don't worry, we simplify this
			 with macros; here's how it really looks.

		  case ENTRY:
       wn_plst(0,0, get_inp_text(Test_tuip, ENTRY), desk_wnp);
       break;
        
       A little better; now you can relax again, InTUItion really is doing
			 all the hard work for you.


H_SLIDER - when the user adjusts the slider, do_dialog returns the proper
					 index.  Now we can read the slider value and print it out.  Both
					 horizontal and vertical sliders would have similar code.
           
		  case H_SLIDER:
       mv_cs( 0, 0, Test_tuip->back_wnp );
       wn_printf(desk_wnp, "%ld", get_sldr_pos(Test_tuip, H_SLIDER));
       break;
           

ICON - when the user clicks on the icon, do_dialog returns the index 
       of ICON. We can then perform any needed action.  Let's just call
       a functionin this case.

		  case ICON:
       do_icon_action();
       break;

BUTTON - when the user clicks on the button, do_dialog returns the index of
				 BUTTON. We can then perform any needed action.  Let's exit the
				 interact function by setting end_flag to ON.

		  case BUTTON:
       end_flag = ON;											/* will cause exit on next pass */
       break;


	  That's all there is to it!  Notice that at the end of the switch
	statement that if the item selected is a button or icon we deselect the
	object and redraw it, since the object would otherwise be left in the
	selected state.  You may elect not to do this depending on what action the
	object is to perform.
